Message routing and failover

Routing decides which channels a message goes out on and which provider delivers each one. When an option can’t deliver, Courier moves to the next, so a user without a push token still gets the email.

Two decisions: channel, then provider

Courier routes every message in two steps. It picks channels from the routing object’s channels list, then picks providers inside each channel in priority order. Each step has its own method:

Decision	Set with	`single`	`all`
Which channels	`routing.method`	Tries channels in order and stops at the first that delivers	Sends on every channel in the list
Which providers	The channel’s `routing_method`	Tries providers in order and stops at the first that delivers (the default)	Sends through every provider on the channel

Failover happens at both levels. Under single, everything after the first option is its backup.

Where routing is set

Most templates carry their routing in a routing strategy: a saved set of channels, fallback order, and providers, attached to the template by ID. Build one in Design Studio or with the API, and every template that uses it picks up your edits on its next send. See . To change routing for one message, pass a routing object on the send:

const { requestId } = await courier.send.message({
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: ["push", "email"],
    },
  },
});

response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {
            "method": "single",
            "channels": ["push", "email"],
        },
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": {
        "method": "single",
        "channels": ["push", "email"]
      }
    }
  }'

response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: ["push", "email"]
    }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Method: string(shared.MessageRoutingMethodSingle),
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("push")},
				{OfString: courier.String("email")},
			},
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(SendMessageParams.Message.Routing.builder()
            .method(SendMessageParams.Message.Routing.Method.SINGLE)
            .addChannel("push")
            .addChannel("email")
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => ['user_id' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => [
      'method' => 'single',
      'channels' => ['push', 'email'],
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new Routing { Method = Method.Single, Channels = ["push", "email"] },
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.routing '{"method": "single", "channels": ["push", "email"]}'

With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123, trying push first and falling back to email.

An inline routing object replaces the strategy’s channel list and method for that message. The strategy’s provider order and channel conditions still apply to the channels you list. With neither, Courier uses the workspace’s default routing, which is { "method": "single", "channels": ["email"] } unless your workspace has saved its own. The recipient’s apply on top of routing. An opted-out topic blocks the send, and a user who picked their own channels for a topic gets those channels instead.

Common patterns

Each pattern is a routing object. Pass it on a send, or save the same shape as a strategy.

Fall back to another channel

Courier tries push, then email, then SMS, and stops at the first that delivers. A user with no push token gets the email, and SMS goes out only if email fails too:

{ "method": "single", "channels": ["push", "email", "sms"] }

Send on every channel

Email and Inbox both go out. Each channel fails over among its own providers, so a failed email doesn’t stop the Inbox message:

{ "method": "all", "channels": ["email", "inbox"] }

Always send one channel, fall back across the rest

An entry in channels can be a nested routing object with its own method. Here the Inbox message always goes out, and the user also gets push, or email if push can’t deliver:

{
  "method": "all",
  "channels": [
    "inbox",
    { "method": "single", "channels": ["push", "email"] }
  ]
}

Design Studio’s Advanced routing scheme saves this shape.

Reach every device on push

APNs and FCM are two providers inside the one push channel, and a channel’s routing_method defaults to single. Courier delivers through the first provider that works and stops, so a user with both an iPhone and an Android tablet gets the notification on one device. Set the push channel’s routing_method to all. It goes in message.channels, keyed by channel name, not in the routing object:

const { requestId } = await courier.send.message({
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: { method: "single", channels: ["push"] },
    channels: {
      push: { routing_method: "all" },
    },
  },
});

response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {"method": "single", "channels": ["push"]},
        "channels": {
            "push": {"routing_method": "all"},
        },
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": { "method": "single", "channels": ["push"] },
      "channels": {
        "push": { "routing_method": "all" }
      }
    }
  }'

response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: { method: "single", channels: ["push"] },
    channels: {
      push: { routing_method: "all" }
    }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Method:   string(shared.MessageRoutingMethodSingle),
			Channels: []shared.MessageRoutingChannelUnionParam{{OfString: courier.String("push")}},
		},
		Channels: shared.MessageChannelsParam{
			"push": shared.ChannelParam{
				RoutingMethod: shared.ChannelRoutingMethodAll,
			},
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(SendMessageParams.Message.Routing.builder()
            .method(SendMessageParams.Message.Routing.Method.SINGLE)
            .addChannel("push")
            .build())
        .channels(MessageChannels.builder()
            .putAdditionalProperty("push", JsonValue.from(java.util.Map.of(
                "routing_method", "all")))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => ['user_id' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => ['method' => 'single', 'channels' => ['push']],
    'channels' => [
      'push' => ['routing_method' => 'all'],
    ],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new Routing { Method = Method.Single, Channels = ["push"] },
        Channels = new Dictionary<string, Channel>()
        {
            { "push", new() { RoutingMethod = RoutingMethod.All } },
        },
    },
};

var response = await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.routing '{"method": "single", "channels": ["push"]}' \
  --message.channels '{"push": {"routing_method": "all"}}'

With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 on push, reaching every device rather than stopping at the first.

A user with only an iPhone gets the same result either way, because Courier skips FCM when the user has no FCM token.

Both providers have to be installed.
routing_method decides how many of the push channel’s providers Courier uses. Install APNs and Firebase FCM under , and Courier includes both.

Send through one provider

Put a provider key such as twilio in channels instead of a channel name, and Courier sends through that provider alone. See .

Channel priority

Inside a channel, Courier tries providers in this order:

The providers listed for that channel in the strategy, in the order you set.
Any other provider you’ve configured for the channel.

Courier skips a provider that can’t reach the recipient, such as an SMS provider for a user with no phone_number, or whose if condition is false. A condition on the channel skips the whole channel. covers writing conditions. To change the provider order for one send, list the providers in message.channels:

{
  "channels": {
    "email": { "providers": ["ses", "sendgrid"] }
  }
}

Failover

Courier moves to the next provider in a channel when one can’t take the message or returns an error. It retries transient errors, such as a rate limit or a dropped connection, before moving on. A channel fails when every provider on it has failed or the recipient has no address for it, and a single route then moves to the next channel. If every option in the route fails, the message fails. Every attempt shows in the message’s .

Timeouts

Courier keeps trying a message for up to 72 hours. To shorten that window, set message.timeout.message in milliseconds. On an Enterprise plan, Courier also moves past a slow provider or channel. It gives each provider 5 minutes and each channel 30 minutes, and you can change both per send. On other plans, a send that sets channel or provider timeouts returns 402.

FAQ

What is the difference between single and all?

single sends through the first channel that delivers and keeps the rest as failover. all sends through every channel in the list at once. A channel’s own routing_method makes the same choice between the providers inside it.

Does a routing object on the send replace the template's routing strategy?

An inline routing object replaces the strategy’s channel list and method for that one message. The strategy’s provider order and channel conditions still apply, so you can reorder channels on a send without losing the rest of the configuration.

How do I send one push to both iOS and Android?

Set the push channel’s routing_method to all in message.channels, and install both APNs and Firebase FCM under Integrations. See reach every device on push.

Is failover available on every plan?

Failover on errors works on every plan: Courier moves to the next provider or channel when one can’t deliver. Moving past a provider or channel that is slow, rather than failed, requires an Enterprise plan.

Get started

Send messages

Journeys

Broadcasts

Design

Recipients

Tenants

Monitoring

Workspaces

Resources

Message routing and failover

Two decisions: channel, then provider

Where routing is set

Common patterns

Fall back to another channel

Send on every channel

Always send one channel, fall back across the rest

Reach every device on push

Send through one provider

Channel priority

Failover

Timeouts

FAQ

​Two decisions: channel, then provider

​Where routing is set

​Common patterns

​Fall back to another channel

​Send on every channel

​Always send one channel, fall back across the rest

​Reach every device on push

​Send through one provider

​Channel priority

​Failover

​Timeouts

​FAQ

Two decisions: channel, then provider

Where routing is set

Common patterns

Fall back to another channel

Send on every channel

Always send one channel, fall back across the rest

Reach every device on push

Send through one provider

Channel priority

Failover

Timeouts

FAQ